home *** CD-ROM | disk | FTP | other *** search
/ Hot Super Models / Hot Super Models.iso / unix / x11 / xv2r1.tar / xv2r1 / extensions / xv / doc / xv-protocol-v2.mem < prev   
Text File  |  1991-07-26  |  21KB  |  655 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.               X Video Extension
  11.              Protocol Description
  12.  
  13.                   Version 2
  14.  
  15.                   25-JUL-91
  16.  
  17.                  David Carver
  18.  
  19.             Digital Equipment Corporation
  20.         Workstation Engineering/Project Athena
  21.  
  22.  
  23.  
  24.  
  25.  
  26.  
  27.  
  28.  
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35.  
  36.  
  37.  
  38.  
  39.  
  40.  
  41.  
  42.  
  43.  
  44.   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - 
  45.   Copyright 1991 by Digital Equipment Corporation, Maynard, Massachusetts, 
  46.   and the Massachusetts Institute of Technology, Cambridge, Massachusetts.
  47.  
  48.                         All Rights Reserved
  49.  
  50.   Permission to use, copy, modify, and distribute this software and its
  51.   documentation for any purpose and without fee is hereby granted, provided
  52.   that the above copyright notice appear in all copies and that both that
  53.   copyright notice and this permission notice appear in supporting
  54.   documentation, and that the names of Digital or MIT not be used in
  55.   advertising or publicity pertaining to distribution of the software
  56.   without specific, written prior permission.
  57.  
  58.   DIGITAL DISCLAIMS ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING 
  59.   ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS, IN NO EVENT SHALL 
  60.   DIGITAL BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR 
  61.   ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER 
  62.   IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING 
  63.   OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.  
  64.   - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
  65.  
  66.  
  67.  
  68.   Preface
  69.   -------
  70.   
  71.     The following is an outline for an X video extension protocol.  It
  72.     is preliminary and subject to change.  My goal in writing this was
  73.     to fix some the shortcomings of existing overly simplistic
  74.     extensions while avoiding pitfalls in an overly complex extension.
  75.   
  76.     Your feedback is desired, and since the major design directions
  77.     have been stable for some time, feel free to hammer on the details
  78.     of the protocol.
  79.  
  80.     When you receive a revision of the document, refer to the changes
  81.     and issues sections to guide your review and analysis.
  82.  
  83.  
  84.   Acknowledgements
  85.   ---------------
  86.  
  87.     The following people have made major contributions to the design of
  88.     the Xv protocol:
  89.  
  90.       Branko Gerovac (DEC/Corporate Research)
  91.       Russ Sasnett (GTE/Project Athena)
  92.       Ralph Swick (DEC/Project Athena)
  93.  
  94.     Many ideas and approaches in Xv were the product of discussions
  95.     with several groups, including
  96.  
  97.       Project Athena's Visual Computing Group
  98.       The MIT X Consortium 
  99.       The MIT Media Lab's Interactive Cinema Group
  100.       
  101.   
  102.   
  103.   Changes
  104.   -------
  105.  
  106.     From version 1.3 to 2.0
  107.  
  108.     -- Changed SetPortControl and GetPortControl to GetPortAttribute
  109.        and SetPortAttribute.
  110.  
  111.     -- Changed QueryBestSize
  112.  
  113.     -- Simplified SelectVideoNotify and SelectPortNotify requests.
  114.  
  115.     -- Changed the way SetPortControl and GetPortControl works.
  116.  
  117.     -- Added a QueryExtension request to return the version and
  118.        revision information of the extension.
  119.  
  120.     -- Changed the name of the QueryVideo request to QueryAdaptors;
  121.        Removed the list of encodings from QueryVideo and added a
  122.        QueryEncodings request.
  123.  
  124.     -- Added a PortNotify event that notifies interested clients that
  125.        a port control has been changed.
  126.  
  127.     -- Added SelectPortNotify request to select for PortNotify events.
  128.  
  129.     -- The XvInterruped reason has been replaced by two new reasons:
  130.        one for when video is preempted by another video request and
  131.        one for when video is terminated because of hard transmission
  132.        or reception errors.
  133.  
  134.     -- Changed the wording of the QueryBestSize request.  Added issue
  135.        about whether or not returned sizes should maintain the
  136.        requested aspect ratio.
  137.  
  138.  
  139.  
  140.   Introduction
  141.   ------------
  142.   
  143.     Video technology is moving very quickly.  Standards for processing
  144.     high resolution video are currently a hot topic of discussion
  145.     internationally, and it will soon be possible to process video
  146.     entirely within the digital domain.  The Xv extension, however,
  147.     does not attempt to address issues of digital video.  Its purpose
  148.     is to provide a mechanism for support of current and near term
  149.     interactive video technology.
  150.     
  151.     It is somewhat ironic that Xv contains nothing particularly
  152.     innovative.  It takes a minimalistic approach, and without a doubt
  153.     it could have been defined years ago, and with several revisions.
  154.     So, the life expectancy of Xv is not long.  Nevertheless, it may
  155.     undergo further revision and experimentation that will help our
  156.     progress towards digital video systems.
  157.   
  158.     One premise of the Xv extension is that the X server is not alone.
  159.     A separate video server is often used to manage other aspects of
  160.     video processing, though the partition between what the X server
  161.     does and what a video server does is a matter of great debate.
  162.  
  163.   
  164.   Model
  165.   -----
  166.   
  167.     This extension models video monitor capabilities in the X Window
  168.     System.  Some advanced monitors support the simultaneous display
  169.     of multiple video signals (into separate windows), and that is
  170.     prepresented here through the ability to display video from
  171.     multiple video input adaptors into X drawables.
  172.   
  173.     Some monitors support multiple video encodings (mostly for
  174.     internationalization purposes) either through switches or
  175.     automatic detection, thus each video adaptor specifies the set of
  176.     encodings it supports.
  177.   
  178.     The requests to display video from an adaptor into a drawable are
  179.     modeled after the core PutImage request, though extended to
  180.     support scaling and source clipping.
  181.   
  182.     Video output is also supported and is symmetric with the video
  183.     input function, though fewer GC components are used.
  184.   
  185.   
  186.   Mechanism
  187.   ---------
  188.   
  189.     The Xv extension does the following:
  190.   
  191.       --  lists available video adaptors
  192.       --  identifies the number of ports each adaptor supports
  193.       --  describes what drawable formats each adaptor supports
  194.       --  describes what video encodings each adaptor supports
  195.       --  displays video from a port to a drawable
  196.       --  captures video from a drawable to a port
  197.       --  grabs and ungrabs ports
  198.       --  sets and gets port attributes
  199.       --  delivers event notification
  200.   
  201.  
  202.   
  203.   Adaptors
  204.   --------
  205.   
  206.     A display may have multiple video input and output adaptors.  An
  207.     adaptor may support multiple simultaneously active ports, and in
  208.     some cases the number of ports has no fixed limit.
  209.   
  210.     An input port receives encoded video data and converts it to a
  211.     stream of data used to update a drawable.  An output port samples
  212.     data from a drawable and produces a stream of encoded video data.
  213.   
  214.     The ADAPTORINFO structure is used to describe a video adaptor.
  215.     
  216.     ADAPTORINFO:
  217.       [base-id: PORT
  218.          num-ports: CARD16
  219.          type: SETofADAPTORTYPE
  220.          formats: LISTofFORMAT
  221.          name: STRING]
  222.   
  223.     ADAPTORTYPE: {Input, Output}
  224.  
  225.     FORMAT:
  226.       [depth: CARD8
  227.        visual: VISUALID]
  228.   
  229.     The base-id field specifies the XID of the first port of the
  230.     adaptor.  The `num-ports' field specifies how many ports the
  231.     adaptor supports.  The ports of the adaptor have XIDs in the range
  232.     [base-id..base-id + num-ports - 1]
  233.  
  234.     The type attribute determines if the adaptor can process video
  235.     input, output, or input and output.  The if the adaptor can
  236.     process input then Input is asserted, if the adaptor can process
  237.     output then Output is asserted.
  238.  
  239.     The drawable depths and visual types supported by the adaptor are
  240.     listed in `formats'.  Note: that when video is being processed for
  241.     pixmaps the visual format is taken to be the visual of the first
  242.     pair that matches the depth of the pixmap.
  243.  
  244.     The name field contains an a vendor specific string that
  245.     identifies the adaptor.
  246.  
  247.     It should be noted that the existence of separate adaptors doesn't
  248.     necessarily imply that simultaneous operation is supported.
  249.  
  250.  
  251.   
  252.   Errors
  253.   ------
  254.   
  255.     Port
  256.   
  257.     A Port error is returned if any request names a PORT that does not
  258.     exist.
  259.  
  260.   
  261.     Encoding
  262.   
  263.     An Encoding error is returned if any request names an ENCODINGID
  264.     that does not exist.
  265.  
  266.  
  267.  
  268.   
  269.   Query Requests
  270.   -------------------
  271.  
  272.     QueryExtension
  273.     ==>
  274.       version: CARD16
  275.       revision: CARD16
  276.  
  277.     The QueryExtension request returns the extension version and
  278.     revision numbers.
  279.  
  280.   
  281.     QueryAdaptors
  282.       win: WINDOW
  283.     ==>
  284.       adaptors: LISTofADAPTORINFO
  285.   
  286.     The QueryAdaptors request returns the video adaptor information for
  287.     the screen of the specified window.
  288.   
  289.     Errors: {Window}
  290.  
  291.  
  292.     QueryEncodings    
  293.       port: PORT
  294.     ==>
  295.       encodings: LISTofENCODINGINFO
  296.  
  297.     The QueryEncodings request returns the list of encodings supported
  298.     by the port adaptor.  Use the SetPortAttribute request to set
  299.     which encoding a port is to process.  The ENCODINGINFO record
  300.     describes an encoding:
  301.  
  302.     ENCODINGINFO:
  303.       [encoding: ENCODINGID
  304.        name: STRING
  305.        width, height: CARD16
  306.        rate: FRACTION]
  307.   
  308.     The `encoding' field identifies an encoding supported by a port.
  309.     Its value is unique for a screen.  Width and height specify the
  310.     size of the video image and rate specifies the rate at which
  311.     fields of image information are encoded.
  312.   
  313.     An encoding is identified by a string that names the encoding.
  314.     Encoding naming conventions need to be established (i.e.,
  315.     something along the lines of font naming, but simpler)
  316.   
  317.     FRACTION
  318.           [numerator, denominator: INT32]
  319.   
  320.     The FRACTION structure is used to specify a fractional number.
  321.  
  322.     Errors: {Port}
  323.  
  324.  
  325.   
  326.   Put Video Requests
  327.   ------------------
  328.   
  329.     PutVideo
  330.       port: PORT
  331.       drawable: DRAWABLE
  332.       gc: GCONTEXT
  333.       vid-x, vid-y: INT16
  334.       vid-w, vid-h: CARD16
  335.       drw-x, drw-y: INT16
  336.       drw-w, drw-h: CARD16
  337.   
  338.     The PutVideo request writes video into a drawable.  The position
  339.     and size of the source rectangle is specified by vid-x, vid-y,
  340.     vid-w, and vid-h.  The position and size of the destination
  341.     rectangle is specified by drw-x, drw-y, drw-w, drw-h.
  342.   
  343.     Video data is clipped to the bounds of the video encoding, scaled
  344.     to the requested drawable region size (or the closest size
  345.     supported), and clipped to the bounds of the drawable.
  346.  
  347.     If video is successfully initiated, a VideoNotify event with
  348.     detail Started is generated for the drawable.  If the port is
  349.     already in use, its video is preempted, and if the new drawable is
  350.     different than the old, a VideoNotify event with detail Preempted
  351.     is generated for the old drawable.  If the port is grabbed by
  352.     another client, this request is ignored, and a VideoNotify event
  353.     with detail Busy is generated for the drawable.  If the port is
  354.     not receiving a valid video signal or if the video signal is
  355.     interrupted while video is active a VideoNotify event with detail
  356.     HardError is generated for the drawable.
  357.  
  358.     GC components: subwindow-mode, clip-x-origin, clip-y-origin, clip-mask.
  359.   
  360.     Errors: {Match, Value, GContext, Port, Alloc}
  361.   
  362.   
  363.     PutStill
  364.       port: PORT
  365.       drawable: DRAWABLE
  366.       gc: GCONTEXT
  367.       vid-x, vid-y: INT16
  368.       vid-w, vid-h: CARD16
  369.       drw-x, drw-y: INT16
  370.       drw-w, drw-h: CARD16
  371.   
  372.     The PutStill request writes a single frame of video into a
  373.     drawable.  The position and size of the source rectangle is
  374.     specified by vid-x, vid-y, vid-w, and vid-h.  The position and
  375.     size of the destination rectangle is specified by drw-x, drw-y,
  376.     drw-w, drw-h.
  377.   
  378.     Video data is clipped to the bounds of the video encoding, scaled
  379.     to the requested drawable region size (or the closest size
  380.     supported) and clipped to the bounds of the drawable.
  381.  
  382.     If the port is grabbed by another client, this request is ignored,
  383.     and a VideoNotify event with detail Busy is generated for the
  384.     drawable.  If the port is not receiving a valid video signal a
  385.     VideoNotify event with detail HardError is generated for the
  386.     drawable.
  387.  
  388.     GC components: subwindow-mode, clip-x-origin, clip-y-origin, clip-mask.
  389.   
  390.     Errors: {Match, Value, GContext, Port, Alloc}
  391.   
  392.   
  393.   
  394.   Get Video Requests
  395.   ------------------
  396.   
  397.     GetVideo
  398.       port: PORT
  399.       drawable: DRAWABLE
  400.       gc: GCONTEXT
  401.       vid-x, vid-y: INT16
  402.       vid-w, vid-h: CARD16
  403.       drw-x, drw-y: INT16
  404.       drw-w, drw-h: CARD16
  405.   
  406.     The GetVideo request outputs video from a drawable.  The position
  407.     and size of the destination rectangle is specified by vid-x,
  408.     vid-y, vid-w, and vid-h.  The position and size of the source
  409.     rectangle is specified by drw-x, drw-y, drw-w, and drw-h.
  410.   
  411.     Drawable data is clipped to the bounds of the drawable, scaled to
  412.     the requested video region size (or the closest size supported)
  413.     and clipped to the bounds of the video encoding.  The contents of
  414.     any region not updated with drawable data is undefined.
  415.  
  416.     If video is successfully initiated, a VideoNotify event with
  417.     detail Started is generated for the drawable.  If the port is
  418.     already in use, its video is preempted, and if the new drawable is
  419.     different than the old, a VideoNotify event with detail Preempted
  420.     is generated for the old drawable.  If the port is grabbed by
  421.     another client, this request is ignored, and a VideoNotify event
  422.     with detail Busy is generated for the drawable.
  423.  
  424.     GC components: subwindow-mode, clip-x-origin, clip-y-origin,
  425.     clip-mask.
  426.   
  427.     Errors: {Match, Value, GContext, Port, Alloc}
  428.   
  429.   
  430.     GetStill
  431.       port: PORT
  432.       drawable: DRAWABLE
  433.       gc: GCONTEXT
  434.       vid-x, vid-y: INT16
  435.       vid-w, vid-h: CARD16
  436.       drw-x, drw-y: INT16
  437.       drw-w, drw-h: CARD16
  438.   
  439.     The GetStill request outputs video from a drawable.  The position
  440.     and size of the destination rectangle is specified by vid-x,
  441.     vid-y, vid-w, and vid-h.  The position and size of the source
  442.     rectangle is specified by drw-x, drw-y, drw-w, and drw-h.
  443.   
  444.     Drawable data is clipped to the bounds of the drawable, scaled to
  445.     the requested video region size (or the closest size supported)
  446.     and clipped to the bounds of the video encoding.  The contents of
  447.     any region not updated with drawable data is undefined.
  448.  
  449.     If the still is successfully captured a VideoNotify event with
  450.     detail Still is generated for the drawable.  If the port is
  451.     grabbed by another client, this request is ignored, and a
  452.     VideoNotify event with detail Busy is generated for the drawable.
  453.  
  454.     GC components: subwindow-mode, clip-x-origin, clip-y-origin,
  455.     clip-mask.
  456.   
  457.     Errors: {Match, Value, GContext, Port, Alloc}
  458.   
  459.   
  460.   
  461.   
  462.   Grab Requests
  463.   -------------
  464.   
  465.     GrabPort
  466.       port: PORT    
  467.       timestamp: {TIMESTAMP, CurrentTime}
  468.     ==>
  469.       status: {Success, AlreadyGrabbed, InvalidTime}
  470.   
  471.     The GrabPort request grabs a port.  While a port is grabbed, only
  472.     video requests from the grabbing client are permitted.
  473.   
  474.     If timestamp specifies a time older than the current port time, a
  475.     status of InvalidTime is returned.  If the port is already grabbed
  476.     by another client, a status of AlreadyGrabbed is returned.
  477.     Otherwise a status of Success is returned. The port time is
  478.     updated when the following requests are processed: GrabPort,
  479.     UngrabPort, PutVideo, PutStill, GetVideo, GetStill
  480.   
  481.     If the port is actively processing video for another client, the
  482.     video is preempted, and an VideoNotify event with detail Preempted
  483.     is generated for its drawable.
  484.  
  485.     Errors: {Port}
  486.   
  487.   
  488.     UngrabPort
  489.       port: PORT    
  490.       timestamp: {TIMESTAMP, CurrentTime}
  491.   
  492.     The UngrabPort request ungrabs a port.  If timestamp specifies a
  493.     time before the last connection request time of this port, the
  494.     request is ignored.
  495.   
  496.     Errors: {Port}
  497.   
  498.  
  499.  
  500.   Other Requests
  501.   --------------
  502.   
  503.     StopVideo
  504.       port: PORT
  505.       drawable: DRAWABLE
  506.   
  507.     The StopVideo request stops active video for the specified port
  508.     and drawable.  If the port isn't processing video, or if it is
  509.     processing video in a different drawable, the request is ignored.
  510.     When video is stopped a VideoNotify event with detail Stopped is
  511.     generated for the associated drawable.
  512.  
  513.     Errors: {Drawable, Port}  
  514.  
  515.   
  516.     SelectVideoNotify
  517.       drawable: DRAWABLE
  518.       onoff: BOOL
  519.   
  520.     The SelectVideoNotify request enables or disables VideoNotify
  521.     event delivery to the requesting client.  VideoNotify events are
  522.     generated when video starts and stops.
  523.  
  524.     Errors: {Drawable}
  525.  
  526.  
  527.     SelectPortNotify
  528.       port: PORT
  529.       onoff: BOOL
  530.   
  531.     The SelectPortNotify request enables or disables PortNotify event
  532.     delivery to the requesting client.  PortNotify events are
  533.     generated when port attributes are changed using SetPortAttribute.
  534.  
  535.     Errors: {Port}
  536.  
  537.   
  538.     QueryBestSize
  539.       port: PORT
  540.       motion: BOOL
  541.       vid-w, vid-h: CARD16
  542.       drw-w, drw-h: CARD16
  543.     ==>
  544.       actual-width, actual-height: CARD16
  545.   
  546.     The QueryBestSize request returns, for the given source size and
  547.     desired destination size, the closest destination size that the
  548.     port adaptor supports.  The returned size will be equal
  549.     or smaller than the requested size if one is supported.  If motion
  550.     is True then the requested size is intended for use with full
  551.     motion video.  If motion is False, the requested size is intended
  552.     for use with stills only.
  553.  
  554.     The retuned size is also chosen to maintain the requested aspect ratio
  555.     if possible.
  556.   
  557.     Errors: {Port}
  558.   
  559.  
  560.     
  561.     SetPortAttribute
  562.       port: PORT
  563.       attribute: ATOM
  564.       value: INT32
  565.   
  566.     The SetPortAttribute request sets the value of a port attribute.
  567.     The port attribute is identified by the attribute atom.  The
  568.     following strings are guaranteed to generate valid atoms using the
  569.     InternAtom request.
  570.  
  571.     String                Type          
  572.     -----------------------------------------------------------------
  573.   
  574.     "XV_ENCODING"         ENCODINGID
  575.     "XV_HUE"              [-1000..1000] 
  576.     "XV_SATURATION"       [-1000..1000] 
  577.     "XV_BRIGHTNESS"       [-1000..1000] 
  578.     "XV_CONTRAST"         [-1000..1000]
  579.   
  580.  
  581.     If the given attribute doesn't match an attribute supported by the
  582.     port adaptor a Match error is generated.  The supplied encoding
  583.     must be one of the encodings listed for the adaptor, otherwise an
  584.     Encoding error is generated.
  585.  
  586.     If the adaptor doesn't support the exact hue, saturation,
  587.     brightness, and contrast levels supplied, the closest levels
  588.     supported are assumed.  The GetPortAttribute request can be used
  589.     to query the resulting levels.
  590.  
  591.     When a SetPortAttribute request is processed a PortNotify event is
  592.     generated for all clients that have requested port change
  593.     notification using SelectPortNotify.
  594.  
  595.     Errors: {Port, Match, Value}
  596.   
  597.   
  598.     GetPortAttribute
  599.       port: PORT
  600.       attribute: ATOM
  601.     ==>
  602.       value: INT32  
  603.         
  604.  
  605.     The GetPortAttribute request returns the current value of the
  606.     attribute identified by the given atom.  If the given atom
  607.     doesn't match an attribute supported by the adaptor a Match
  608.     error is generated.
  609.  
  610.     Errors: {Port, Match}
  611.  
  612.  
  613.  
  614.   Events
  615.   ------
  616.   
  617.     VideoNotify
  618.       drawable: DRAWABLE
  619.       port: PORT
  620.       reason: REASON
  621.       time: TIMESTAMP
  622.  
  623.     REASON: {Started, Still, Stopped, Busy, Preempted, HardError}
  624.  
  625.     A VideoNotify event is generated when video activity is started,
  626.     stopped, or unable to proceed in a drawable.
  627.  
  628.     A Started reason is generated when video starts in a drawable.
  629.  
  630.     A Stopped reason is generated when video is stopped in a
  631.     drawable upon request.
  632.  
  633.     A Busy reason is generated when a put or get request cannot
  634.     proceed because the port is grabbed by another client.
  635.  
  636.     A Preempted reason is generated when video is stopped by a
  637.     conflicting request.
  638.   
  639.     A HardError reason is generated when the video port cannot
  640.     initiate or continue processing a video request because of an
  641.     underlying transmission or reception error.
  642.   
  643.  
  644.     PortNotify
  645.       port: PORT
  646.       attribute: ATOM
  647.       value: INT32
  648.       time: TIMESTAMP
  649.   
  650.     The PortNotify event is generated when a SetPortAttribute request
  651.     is processed.  The event is delivered to all clients that have
  652.     performed a SelectPortNotify request for the port.  The event
  653.     contains the atom identifying the attribute that changed, and the
  654.     new value of that attribute.
  655.